@paprika/list-box

@paprika/list-box - 1.2.1-alpha.3

Description

The ListBox component allows users to select one or more options from a list contained within the component

Installation

yarn add @paprika/list-box

or with npm:

npm install @paprika/list-box

Props

ListBox

Prop	Type	required	default	Description
children	node	true	-	Child of type <ListBox.Option />, <ListBox.Divider />, etc
hasImplicitAll	bool	false	-	Has implicit "All items selected" value when no item is selected
height	number	true	-	Indicate which is the height for the options container
isDisabled	bool	false	-	Disables the ListBox if true
isInline	bool	false	-	This options will display the list-box without the Popover
isMulti	bool	false	-	Let the user to select multiple options at same time
isOpen	bool	false	-	Indicates if the popover is visible
onChange	func	false	-	Callback returning the current selection on the ListBox
placeholder	string	true	-	Defaults label to display when the ListBox has not option selected
size	[ ListBoxContainer.types.size.SMALL, ListBoxContainer.types.size.MEDIUM, ListBoxContainer.types.size.LARGE]	false	-	Size of the trigger and options (font size, height, padding, etc).

Box

Prop	Type	required	default	Description
children	node	true	-	Body content of the box.

ListBox.Divider

Prop	Type	required	default	Description
isDisabled	bool	false	true	isDisable is use internally as a default prop

the prop is read by the option/helpers/optionState.js which is assigned in the store it helps to ignore the divider while using the keyboard. see: options/helpers/options.js| |children|node|false|null| |

ListBox.Filter

Prop	Type	required	default	Description
a11yText	string	false	null	Descriptive a11y text for assistive technologies. By default, text from children node will be used.
filter	func	false	null	Filters the list
hasSearchIcon	bool	false	true	If true displays a search icon
noResultsMessage	string	false	null	Message displayed if no results are found
onChangeFilter	func	false	null	Callback to be executed when the value is changed
onKeyDown	func	false	null	Callback to be executed when a key is pressed
placeholder	string	false	null	Displays a placeholder
renderFilter	func	false	null	Render function for filter
value	string	false	null	Sets a value for filter

ListBox.Footer

Prop	Type	required	default	Description
isAcceptVisible	bool	false	true	If true it makes the accept button visible
isCancelVisible	bool	false	true	If true it makes the cancel button visible
isClearVisible	bool	false	true	If true it makes the clear button visible
isDisabled	bool	false	false	If true it makes the footer disabled
kindAccept	[ Button.types.kind.PRIMARY, Button.types.kind.MINOR]	false	Button.types.kind.PRIMARY	Sets what kind the accept button will be
kindCancel	[ Button.types.kind.PRIMARY, Button.types.kind.MINOR]	false	Button.types.kind.MINOR	Sets what kind the cancel button will be
kindClear	[ Button.types.kind.PRIMARY, Button.types.kind.MINOR]	false	Button.types.kind.MINOR	Sets what kind the cancel button will be
labelAccept	string	false	null	Sets the label for the accept button
labelCancel	string	false	null	Sets the label for the cancel button
labelClear	string	false	null	Sets the label for the clear button
onClickAccept	func	false	null	Callback to be executed when the accept button is clicked or activated by keyboard.
onClickCancel	func	false	null	Callback to be executed when the cancel button is clicked or activated by keyboard.
onClickClear	func	false	null	Callback to be executed when the clear button is clicked or activated by keyboard.
renderExtraButton	func	false	() => {}	Render an extra button beside the clear button
size	[ Button.types.size.SMALL, Button.types.size.MEDIUM, Button.types.size.LARGE]	false	Button.types.size.SMALL	Determines the size of the footer

ListBox.Option

Prop	Type	required	default	Description
children	[node,func]	true	-	String, number or JSX content
isSelected	bool	false	null
defaultIsSelected	bool	false	null	Describe if the option started as selected or not
isDisabled	bool	false	false	Describe if the option is enable or not
isHidden	bool	false	false	Describe if the option is hidden or not
label	string	false	null	When the children are not a String, label should need to be add so the filter can work
onClick	func	false	null	Callback for the clicking event
value	any	false	null	Value of your option this can be any data structure
preventDefaultOnSelect	bool	false	false	Internal prop, which shouldn't be documented

ListBox.Popover

Prop	Type	required	default	Description
children	node	false	-	Body content of the PopOver.
zIndex	number	false	100	Sets the z-index value of the PopOver

ListBox.RawItem

Prop	Type	required	default	Description
preventDefaultOnSelect	bool	false	true

ListBox.Trigger

Prop	Type	required	default	Description
clearIcon	node	false	null	Custom clear icon
children	[node,func]	false	<React.Fragment />	Body content of the trigger.
hasClearButton	bool	false	true	If true it adds a clear button
hasImplicitAll	bool	false	false	Has implicit "All items selected" value when no item is selected
label	string	false	null	Override the label with a custom one.
onClickClear	func	false	null	Callback to be executed when the clear button is clicked or activated by keyboard.
onClickFooterAccept	func	false	null	Callback to be executed when the accept button is clicked or activated by keyboard.
placeholder	string	false	"Select..."	Sets a placeholder for the trigger
isHidden	bool	false	false	If true the trigger will be hidden

WithTags

Prop	Type	required	default	Description
children	arrayOf	true	-	Child of type <ListBox.Option />, <ListBox.Divider />, etc
filter	func	false	undefined	filter function for the ListBoxWithTags can be pair with ListBoxWithTags.filter
noResultsMessage	node	false	null	String message to be display when there are not results
onChange	func	false	() => {}	Callback whenever the user change a selection on the ListBoxWithTags
onAddCustomOption	func	false	null	Callback whenever the user input a new custom option like [e-mail], pass undefined to ignore this behaviour
onRemove	func	false	() => {}	Callback once a pill is remove from the Trigger
customOptionRegex	instanceOf	false	/^.+@.+..+$/	Regex that match the input of the user and reports to onAddCustomOption. The default is a basic email regex
renderPill	func	false	null	Render prop to override the default Pill style, see example for it's uses.
selectedOptions	arrayOf	false	null	An array of id that helps the ListBoxWithTags to known what elements are selected
pillLabelKey	string	false	null	Provides an alternative for rendering the Pill label instead of using the default [{label:value}] coming from the og data
allOptionsAreSelected	bool	false	false	When this is true, it will display a message indicating all options are selected without showing the popover nor the search input
allOptionsAreSelectedMessage	string	false	""	Message to display when all options have been selected

For a basic ListBox

import ListBox from "@paprika/list-box";

function Component() {
  return (
    <ListBox onChange={changeHandler}>
      <ListBox.Option>Option 1</ListBox.Option>
      <ListBox.Option>Option 2</ListBox.Option>
    </ListBox>
  );
}

With Filter

import ListBox from "@paprika/list-box";

function Component() {
  return (
    <ListBox onChange={changeHandler}>
      <ListBox.Filter />
      <ListBox.Option>Option 1</ListBox.Option>
      <ListBox.Option>Option 2</ListBox.Option>
    </ListBox>
  );
}

Links

• Storybook Showcase
• GitHub source code
• Create GitHub issue
• CHANGELOG